/*
 ------------------------------------------------------------------------------
 Copyright (C) 1996-2001 Id Software, Inc.

 This file is part of the Quake source code.

 The Quake source code is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or (at your
 option) any later version.

 The Quake source code is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
 more details.

 You should have received a copy of the GNU General Public License along with
 the Quake source code; if not, write to the Free Software Foundation, Inc.,
 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 ------------------------------------------------------------------------------
*/


//
// fileSystem.h - handle based file system
//


#ifndef __FILESYSTEM_H__
#define __FILESYSTEM_H__


// Reads data from a file, properly handling partial reads.
// Returns the number of bytes read.
int				FS_Read (fileHandle_t f, void *buffer, int size);

// Writes data to a file, properly handling partial writes.
// Returns the number of bytes written.
int				FS_Write (fileHandle_t f, const void *buffer, int size);

// Writes formatted text to a file.
// Returns the number of characters written.
int				FS_Printf (fileHandle_t f, const char *fmt, ...);

// Returns the offset in a file
int				FS_Tell (fileHandle_t f);

// Seeks on a file
void			FS_Seek (fileHandle_t f, int offset, fsOrigin_t origin);

// Opens the given file for reading, writing, or appending. Will create any
// needed subdirectories.
// Returns file size, or -1 if the file wasn't found or an error occurred.
int				FS_OpenFile (const char *name, fsMode_t mode, fileHandle_t *f);

// Closes the given file
void			FS_CloseFile (fileHandle_t f);

// Removes the given file
bool			FS_RemoveFile (const char *name);

// Returns true if the given file exists in the current game directory.
// This is to determine if writing a file will cause any overwrites.
bool			FS_FileExists (const char *name);

// Looks for a file in the search paths.
// Returns file availability and optionally sets the source path if found.
findFile_t		FS_FindFile (const char *name, char sourcePath[MAX_PATH_LENGTH]);

// Reads a complete file.
// Returns file size, or -1 if the file wasn't found or an error occurred.
// A NULL buffer will just return the file size without loading as a quick
// check for existance (-1 == not present).
// Appends a trailing 0, so string operations are always safe.
int				FS_ReadFile (const char *name, void **buffer);

// Frees the memory allocated by FS_ReadFile
void			FS_FreeFile (const void *buffer);

// Writes a complete file. Will create any needed subdirectories.
// Returns true if the file was written.
bool			FS_WriteFile (const char *name, const void *buffer, int size);

// Extracts the given dynamic library from a pack file and sets the fully
// qualified path to the extracted file (appending suffix and extension
// appropriate for the underlying platform).
// Returns false if the dynamic library could not be found or extracted.
bool			FS_ExtractLibrary (const char *baseName, char libPath[MAX_PATH_LENGTH]);

// Loads and caches the given file, or returns the cached file
void *			FS_CacheFile (const char *name);

// Flushes the file cache
void			FS_FlushCache ();

// Returns a list of files and subdirectories that match the given extension
// (which must include a leading '.' and must not contain wildcards).
// If extension is NULL, all the files will be returned and all the
// subdirectories ignored.
// If extension is "/", all the subdirectories will be returned and all the
// files ignored.
// The returned list can optionally be sorted.
const char **	FS_ListFiles (const char *path, const char *extension, bool sort, int *numFiles);

// Returns a list of files and subdirectories that match the given filter.
// The returned list can optionally be sorted.
const char **	FS_ListFilteredFiles (const char *filter, bool sort, int *numFiles);

// Frees the memory allocated by FS_ListFiles and FS_ListFilteredFiles
void			FS_FreeFileList (const char **fileList);

// Initializes the file system
void			FS_Init ();

// Shuts down the file system
void			FS_Shutdown ();


#endif	// __FILESYSTEM_H__